Skip to main content

Variant Image Tagging Guide

Overview​

When the "Hide unselected variant media" setting is enabled in the Product Media Gallery block, you can now associate multiple images with each variant using a simple alt text tagging system.

How It Works​

The gallery will hide images based on two criteria:

  1. Original Shopify behavior: Hides images that are directly attached to other variants (the single image per variant)
  2. Enhanced behavior: Hides images tagged for other variants in their alt text

How to Tag Images​

Add a tag to the alt text of each image using this format:

variant-{option1}-{option2}-{option3}

Examples​

Product with Color and Size variants:

For a "Red" and "Small" variant:

  • Alt text: Red t-shirt front view variant-red-small
  • Alt text: Red t-shirt back view variant-red-small
  • Alt text: Red t-shirt detail variant-red-small

For a "Blue" and "Large" variant:

  • Alt text: Blue t-shirt front view variant-blue-large
  • Alt text: Blue t-shirt back view variant-blue-large

Product with single option (Color only):

For a "Red" variant:

  • Alt text: Product image variant-red

Important Rules​

  1. Use lowercase and hyphens: Variant tags are automatically converted to lowercase with hyphens (using Liquid's handleize filter)

    • "Red Small" becomes variant-red-small
    • "Dark Blue" becomes variant-dark-blue
    • "XL" becomes variant-xl

  2. Order matters: Options must be in the same order as defined in Shopify:

    • If your options are "Color" then "Size", use variant-red-small (not variant-small-red)

  3. Tag placement: The variant- tag can appear anywhere in the alt text

    • ✅ Product name variant-red-small lifestyle shot
    • ✅ variant-red-small - Product detail view
    • ✅ Beautiful red shirt variant-red-small on model

  4. Untagged images: Images without a variant- tag in their alt text will show for ALL variants

Setting Up in Shopify Admin​

  1. Go to Products > Select your product
  2. Scroll to Media section
  3. For each image, click the image options and select Edit
  4. In the Alt text field, add your variant tag
  5. Click Done

Example Setup for a T-Shirt​

Let's say you have a t-shirt with these variants:

  • Red / Small
  • Red / Large
  • Blue / Small
  • Blue / Large

And 8 images total (4 images per color):

Red variant images:

Alt text: "Red t-shirt front view variant-red-small"
Alt text: "Red t-shirt back view variant-red-small"
Alt text: "Red t-shirt on model variant-red-small"
Alt text: "Red t-shirt detail close-up variant-red-small"

Blue variant images:

Alt text: "Blue t-shirt front view variant-blue-small"
Alt text: "Blue t-shirt back view variant-blue-small"
Alt text: "Blue t-shirt on model variant-blue-small"
Alt text: "Blue t-shirt detail close-up variant-blue-small"

Result: When a customer selects "Red / Small", they'll only see the 4 red images. When they select "Blue / Small", they'll only see the 4 blue images.

Sharing Images Across Similar Variants​

If you want the same images to show for multiple similar variants (e.g., all sizes of the same color), you have two options:

Option 1: Tag with multiple variant combinations​

Add multiple variant tags to the alt text:

Alt text: "Red t-shirt detail variant-red-small variant-red-medium variant-red-large"

Option 2: Don't include the option in the tag​

If you only want to filter by color (not size), use tags without the size:

Alt text: "Red t-shirt detail variant-red"

⚠️ Warning: This approach requires custom code modifications to the theme and is not currently supported out of the box.

Enabling the Feature​

  1. Go to Theme Customizer
  2. Navigate to your product template
  3. Select the Product Media Gallery block
  4. Enable "Hide unselected variant media"
  5. (Optional) Enable "Hide untagged images (strict mode)" if you want ONLY tagged images to show
  6. Save your changes

Setting Options​

Hide unselected variant media (Required)

  • Enables the variant filtering feature
  • Hides images attached to other variants
  • Hides images tagged for other variants

Hide untagged images (strict mode) (Optional)

  • Only appears when "Hide unselected variant media" is enabled
  • When OFF: Untagged images show for all variants (default)
  • When ON: Only images with matching variant tags show (strict mode)

Troubleshooting​

Images aren't hiding:

  • Check that "Hide unselected variant media" is enabled
  • Verify alt text tags match the exact variant option names (lowercase with hyphens)
  • Confirm option order matches Shopify's option order

Some images show for wrong variants:

  • Make sure there are no typos in variant tags
  • Check that option names are handleized correctly (spaces → hyphens, lowercase)

Images disappear completely:

  • Ensure at least one image is tagged for each variant
  • Check that untagged "general" images exist if needed

Technical Details​

The system uses Liquid's handleize filter to convert variant option values:

  • Converts to lowercase
  • Replaces spaces with hyphens
  • Removes special characters

Example transformations:

  • "Dark Blue" → dark-blue
  • "Extra Large" → extra-large
  • "Red/Orange" → red-orange

Best Practices​

  1. Always include descriptive alt text for accessibility, with the variant tag as a suffix
  2. Use consistent naming across all products
  3. Tag all variant-specific images to avoid confusion
  4. Keep some untagged images for general product information that applies to all variants
  5. Test thoroughly after setting up to ensure correct images show for each variant